% Copyright 2006 by Till Tantau
%
% This file may be distributed and/or modified
%
% 1. under the LaTeX Project Public License and/or
% 2. under the GNU Free Documentation License.
%
% See the file doc/generic/pgf/licenses/LICENSE for more details.


% \section{Introduction}
\section{介绍}

% Welcome to the documentation of \tikzname\ and the underlying
% \pgfname\ system. What began as a small La\TeX\ style for creating the 
% graphics in my (Till Tantau's) PhD thesis directly with pdf\LaTeX\ has now
% grown to become a full-flung graphics language with a manual of over a
% thousand pages. The wealth of options offered by \tikzname\ is often
% daunting to beginners; but fortunately this documentation comes with a
% number slowly-paced tutorials that will teach you almost all you
% should know about \tikzname\ without your having to read the rest.

欢迎阅读\tikzname\ 文档并运行\pgfname\ 系统。它们源于一个用于生成图形
的很小的La\TeX\ 宏包，那时我(Till Tantau)还在博士论文中直接用
pdf\LaTeX\ 生成图形，现在它已经成为一门功能丰富的图形语言，仅手册就已
逾千页。\tikzname\ 中的大量选项经常使初学者畏惧不前；但幸运的是，本文
档采用大量渐进式的教程告诉你关于\tikzname\ 所应知道的一切，你甚至不必
阅读其余的内容。

% I wish to start with the questions ``What is \tikzname?''
% Basically, it just defines a number of \TeX\ commands that draw
% graphics. For example, the code |\tikz \draw (0pt,0pt) -- (20pt,6pt);|
% yields the line \tikz \draw (0pt,0pt) -- (20pt,6pt); and the code
% |\tikz \fill[orange] (1ex,1ex) circle (1ex);| yields \tikz
% \fill[orange] (1ex,1ex) circle (1ex);. In a sense, when you use
% \tikzname\ you ``program'' your graphics, just as you ``program'' your
% document when you use \TeX. This also explains the name: \tikzname\
% is a recursive accronym in the tradition of ``\textsc{gnu} is not
% unix'' and means ``\tikzname\ ist \emph{kein} Zeichenprogramm,'' which
% translates to ``\tikzname\ is not a drawing program,'' cautioning the
% reader as to what to expect. With \tikzname\ you get all the advantages of the
% ``\TeX-approach to typesetting'' for your graphics: quick creation of
% simple graphics, precise positioning, the use of macros, often
% superior typography. You also inherit all the disadvantages: steep
% learning curve, no \textsc{wysiwyg}, small changes require a long
% recompilation time, and the code does not really ``show'' how things
% will look like. 

我希望从“\tikzname\ 是什么？”开始。它基本上是一组画图的\TeX\ 命令。
举例来说，代码|\tikz \draw (0pt,0pt) -- (20pt,6pt);|得到直线\tikz
\draw (0pt,0pt) -- (20pt,6pt);而代码|\tikz \fill[orange] (1ex,1ex)
circle (1ex);| 则生成了 \tikz \fill[orange] (1ex,1ex) circle (1ex);。
某种意义上，你是在用\tikzname\ 编程生成图形，这和你使用\TeX\ 编程生成
文档是一样的。这也是它名字的意义：\tikzname\ 是“\tikzname\ ist
\emph{kein} Zeichenprogramm”的迭代缩写，这也是沿袭了“\textsc{gnu} is
not unix”的传统。它意味着“\tikzname\ 不是一个画图系统”，警示读者的
误解。\tikzname\ 使你可以充分利用“\TeX\ 的编译方式”生成图形：快速生成
简单的图形，准确的定位，宏的利用，还有超级好的排版。你同样还要遭遇所有
\TeX\ 的缺点：陡峭的学习曲线，没有“所见即所得”，微小的改动也需要长时间的
再编译，还有代码并不显示它将呈现的样子。

% Now that we know what \tikzname\ is, what about ``\pgfname''?
% As mentioned earlier, \tikzname\ started out as a project to implement
% \TeX\ graphics macros that can be used both with pdf\LaTeX\ and also
% with the classical (PostScript-based) \LaTeX. In other words, I wanted
% to implement a ``portable graphics format'' for \TeX\ -- hence the
% name \pgfname. These early macros are still around and they form the
% ``basic layer'' of the system described in this manual, but most of
% the interaction an author has theses days is with \tikzname\ -- which
% has become a whole language of its own.

现在我们了解了\tikzname\ 是什么，那么“\pgfname”又是什么呢？如前所述，
\tikzname\ 作为一个项目致力于\TeX\ 图形命令宏的实现，这组宏可以应用于
pdf\LaTeX\ 和其它典型的（基于PostScript）\LaTeX\ 驱动中。换言之，我想实
现一个用于\TeX\ 的“便携的图形格式”，这也是\pgfname\ 的来历。这些早期
的宏现在依然有效并构成了手册中所述系统的“基本层”，但作者用于交互的主
体却已经是\tikzname\ ，它本身即为一种完整的语言。

% \subsection{The Layers Below \tikzname}
\subsection{\tikzname 的下层}

% It turns out that there are actually \emph{two} layers below \tikzname:
在\tikzname 以下实际有\emph{两个}层次：

\begin{description}
\item[系统层：]
  % This layer provides a complete abstraction of what is
  % going on ``in the driver.'' The driver is a program like |dvips| or
  % |dvipdfm| that takes a |.dvi| file as input and generates a |.ps| or
  % a |.pdf| file. (The |pdftex| program also counts as a driver, even
  % though it does not take a |.dvi| file as input. Never mind.) Each
  % driver has its own syntax for the generation of graphics, causing
  % headaches to everyone who wants to create graphics in a portable
  % way. \pgfname's system layer ``abstracts away'' these
  % differences. For example, the system command
  % |\pgfsys@lineto{10pt}{10pt}| extends the current path  to the coordinate
  % $(10\mathrm{pt},10\mathrm{pt})$ of the current
  % |{pgfpicture}|. Depending on whether |dvips|,
  % |dvipdfm|, or |pdftex| is used to process the document, the system
  % command will be converted to different |\special| commands.
  % The system layer is as ``minimalistic'' as possible since each
  % additional command makes it more work to port \pgfname\ to a new
  % driver.

  % As a user, you will not use the system layer directly.
  该层对“驱动”做了一个彻底的抽象。所谓驱动，就是一个类似|dvips|或
  |dvipdfm|程序，它将输入的|.dvi|文件转为|.ps|或|.pdf|文件。
  （|pdftex|程序也一样称为驱动，即使它不将|.dvi|文件作为输入。别太介意
  哟。）每个驱动都有属于自己的生成图形的语法，这使每个想用一种可移植方
  式生成图形的人都头疼不已。\pgfname\ 的系统层将不同驱动的语法间的差别“抽取了出
  去”。比如，系统命令|\pgfsys@lineto{10pt}{10pt}|将路径延伸到
  |{pgfpicture}|中的坐标$(10\mathrm{pt},10\mathrm{pt})$。 
  根据具体用于处理文档的程序（驱动），如|dvips|、|dvipdfm|、或|pdftex|，系统命
  令将被转换为不同的|\special|命令。
  系统层尽可能是一位“极简主义者”，因为每多一个额外的命令，在将
  \pgfname\ 引入到新驱动中就会多做一些工作。

  作为用户，你不会直接用到系统层。
  
\item[基础层:]
  % The basic layer provides a set of basic commands that allow
  % you to produce complex graphics in a much easier manner than by using
  % the system layer directly. For example,  the system layer provides
  % no commands for creating circles since circles can be composed from
  % the more basic B\'ezier curves (well, almost). However, as a user you
  % will want to have a simple command to create circles
  % (at least I do) instead of having to write down half a page of
  % B\'ezier curve support coordinates. Thus, the basic layer provides a
  % command |\pgfpathcircle| that generates the necessary curve
  % coordinates for you.

  基础层提供了一整套基本命令，可以让你用更加简易的方式画出复杂的图形，
  而不是直接使用系统层命令。比如，系统层并未提供生成圆的命令，因为圆可
  以用更为基础的B\'ezier曲线生成。然而，作为用户，你需要有一个生成圆的
  简单命令（至少我是需要的），而不是必须写出半页的B\'ezier曲线坐标。这
  样，基础层就给出了一个命令|\pgfpathcircle|让你生成所需要的曲线坐标。

  % The basic layer consists of a \emph{core}, which consists of
  % several interdependent packages that can only be loaded \emph{en
  %   bloc,} and additional \emph{modules} that extend the core by more
  % special-purpose commands like node management or a plotting
  % interface. For instance, the \textsc{beamer} package uses only the
  % core and not, say, the |shapes| modules.

  基础层包含一个\emph{内核}，在内核中有几个相互依赖的宏包，这些宏包只
  能被整体加载，而其它\emph{模块}则是采用特定目的命令由内核扩展出
  来的，比如节点管理或绘制界面。举例来说，\textsc{beamer}宏包只使用了
  内核，而没用引用比如|shapes|的其它模块。

\end{description}  

% In theory, \tikzname itself is just one of several possible
% ``frontends,'' which are sets of commands or a special syntax that
% makes using the basic layer easier. A problem with directly using the
% basic layer is that code written for this layer is often too
% ``verbose.'' For example, to draw a simple 
% triangle, you may need as many as five commands when using the basic
% layer: One for beginning a path at the first corner of the triangle,
% one for extending the path to the second corner, one for going to
% the third, one for closing the path, and one for actually painting
% the triangle (as opposed to filling it). With the \tikzname\ frontend
% all this boils down to a single simple \textsc{metafont}-like
% command:

理论上，\tikzname 本身只是“前端”中的一种，所谓“前端”是若干命令或特
殊语法的组合，它使得基础层用起来更加容易。直接使用基础层会使得代码过于
冗长。举例来说，要画一个简单的三角形，使用基础层的话你得用5条命令：第
一条是在三角形第一个角处开始画一条路径，然后向第二个角延伸，再转向第三
个，再闭合这条路径，最后才能实际绘制这个三角形（而非填充它）。而使用
\tikzname\ 前端，这些烦杂动作将简化为类似于\textsc{metafont}的命令：

\begin{verbatim}
\draw (0,0) -- (1,0) -- (1,1) -- cycle;
\end{verbatim}

% In practice, \tikzname\ is the only ``serious'' frontend for \pgfname. It
% gives you access to all features of \pgfname, but it is intended to be
% easy to use. The syntax is a mixture of \textsc{metafont} and
% \textsc{pstricks} and some ideas of myself. There are other frontends
% besides \tikzname, but they are more intended as ``technology
% studies'' and less as serious alternatives to \tikzname. In
% particular, the |pgfpict2e| frontend   reimplements the standard
% \LaTeX\ |{picture}|  environment and 
% commands like |\line| or |\vector| 
% using the \pgfname\ basic layer. This layer is not really ``necessary''
% since the |pict2e.sty| package does at least as good a job at
% reimplementing the |{picture}| environment. Rather, the idea
% behind this package is to have a simple demonstration of how a
% frontend can be implemented. 

\tikzname\ 其实是\pgfname\ 唯一“真正的”前端。它可以使你使用\pgfname\
所有功能，却非常易用。它的语法是\textsc{metafont}和\textsc{pstricks}的
混合体，其中还有我自己的一些想法。在\tikzname\ 之外还有些前端，但更类
似于“技术研究”，而不是有意作为\tikzname\ 的替代品。|pgfpic2e| 前端重
新实现了标准\LaTeX\ |{picture}| 环境和类似\pgfname\ 基础层中|\line|和
|\vector|的命令。这一层并非真正“必需”，因为至少|pict2e.sty| 宏包可以
和重实现的|{picture}|环境同样出色地完成工作。该宏包其实是想证明实现前
端是一件很容易的事。

% Since most users will only use \tikzname\ and almost no one will use
% the system layer directly, this manual is mainly about \tikzname\ in
% the first parts; the basic layer and the system layer are explained at
% the end.

由于大多数用户只使用\tikzname\ 而没人直接用系统层，本手册首先介绍
\tikzname\ ；基础层和系统层在后面再作介绍。

% \subsection{Comparison with Other Graphics Packages}
\subsection{同其它图形宏包比较}

% \tikzname\ is not the only graphics package for \TeX. In the following,
% I try to give a reasonably fair comparison of \tikzname\ and
% other packages.
\tikzname\ is not the only graphics package for \TeX. In the following,
I try to give a reasonably fair comparison of \tikzname\ and
other packages.

\tikzname\ 不是\TeX\ 中惟一的图形宏包。下面我试着对\tikzname\ 和其它
宏包作一个理性公平的比较。

\begin{enumerate}
\item
  The standard \LaTeX\ |{picture}| environment allows you to create
  simple graphics, but little more. This is certainly not
  due to a lack of knowledge or imagination on the part of
  \LaTeX's designer(s). Rather, this is the price paid for the
  |{picture}| environment's portability: It works together with all
  backend drivers.
\item
  The |pstricks| package is certainly powerful enough to create
  any conceivable kind of graphic, but it is not really portable. Most
  importantly, it does not work with |pdftex| nor with any other
  driver that produces anything but PostScript code.

  Compared to \tikzname, |pstricks| has a similar support base. There
  are many nice extra packages for special purpose situations that have
  been contributed by users over the last decade.
  The \tikzname\ syntax is more consistent than the |pstricks| syntax
  as \tikzname\ was developed ``in a more centralized manner'' and
  also ``with the shortcomings on |pstricks| in mind.''
\item
  The |xypic| package is an older package for creating
  graphics. However, it is more difficult to use and to learn because
  the syntax and the documentation are a bit cryptic.
\item
  The |dratex| package is a small graphic package for creating a
  graphics. Compared to the other package, including \tikzname, it is
  very small, which may or may not be an advantage.
\item
  The |metapost| program is a powerful alternative to
  \tikzname. It used to be an external program, which entailed a
  bunch of problems, but in Lua\TeX\ it is now build in. An obstacle
  with |metapost| is the inclusion of labels. This is \emph{much}
  easier to achieve using \pgfname. 
\item
  The |xfig| program is an important alternative to \tikzname\ for
  users who do not wish to ``program'' their graphics as is necessary
  with \tikzname\ and the other packages above. There is a conversion
  program that will convert |xfig| graphics to \tikzname.
\end{enumerate}


% \subsection{Utility Packages}
\subsection{工具包}

The \pgfname\ package comes along with a number of utility package that
are not really about creating graphics and which can be used
independently of \pgfname. However, they are bundled with \pgfname,
partly out of convenience, partly because their functionality is
closely intertwined with \pgfname. These utility packages are:
\begin{enumerate}
\item The |pgfkeys| package defines a powerful key management
  facility. It can be used completely independently of \pgfname.
\item The |pgffor| package defines a useful |\foreach| statement.
\item The |pgfcalendar| package defines macros for creating
  calendars. Typically, these calendars will be rendered using
  \pgfname's graphic engine, but you can use |pgfcalendar| also
  typeset calendars using normal text. The package also defines
  commands for ``working'' with dates.
\item The |pgfpages| package is used to assemble several pages into a
  single page. It provides commands for assembling several
  ``virtual pages'' into a single ``physical page.'' The idea is that
  whenever \TeX\ has a page ready for ``shipout,'' |pgfpages| interrupts
  this shipout and instead stores the page to be shipped out in a
  special box. When enough ``virtual pages'' have been accumulated in
  this way, they are scaled down and arranged on a ``physical page,''
  which then \emph{really} shipped out. This mechanism allows you to
  create ``two page on one page'' versions of a document directly inside
  \LaTeX\ without the use of any external programs. However,
  |pgfpages| can do quite a lot more than that. You can use it to put
  logos and watermark on pages, print up to 16 pages on one page, add
  borders to pages, and more.
\end{enumerate}



% \subsection{How to Read This Manual}
\subsection{如何阅读本手册}

This manual describes both the design of \tikzname\ and
its usage. The organization is very roughly according to
``user-friendliness.'' The commands and subpackages that are easiest
and most frequently used are described first, more low-level and
esoteric features are discussed later.

If you have not yet installed \tikzname, please read the installation
first. Second, it might be a good idea to read the tutorial. Finally,
you might wish to skim through the description of \tikzname. Typically,
you will not need to read the sections on the basic layer. You will
only need to read the part on the system layer if you intend to write
your own frontend or if you wish to port \pgfname\ to a new driver.

The ``public'' commands and environments provided by the system
are described throughout the text. In each such description, the
described command, environment or option is printed in red. Text shown
in green is optional and can be left out.


% \subsection{Authors and Acknowledgements}
\subsection{作者和致谢}
\label{section-authors}

% The bulk of the \pgfname\ system and its documentation was written by
% Till Tantau. A further member of the main team is Mark Wibrow, who
% is responsible, for example, for the \pgfname\ mathematical engine,
% many shapes, the decoration engine, and matrices. The third member is
% Christian Feuers\"anger who contributed the floating point library,
% image externalization, extended key processing, and automatic hyperlinks
% in the manual.

\pgfname\ 系统的主体和文档由Till Tantau创作。团队的另一名成员是Mark
Wibrow，它负责的工作包括，\pgfname\ 的数学引擎、许多形状、装饰引擎、和
矩阵。第三位成员是Christian Feuers\"anger，他贡献了浮点库、图形外部化、
扩展键处理、和手册中的自动链接。

% Furthermore, occasional contributions have been made by Christophe
% Jorssen, Jin-Hwan Cho, Olivier Binda, Matthias Schulz, Ren\'ee Ahrens,
% Stephan Schuster, and Thomas Neumann.

其它贡献来自于Christophe Jorssen、Jin-Hwan Cho、Olivier Binda、
Matthias Schulz、Ren\'ee Ahrens、Stephan Schuster、和Thomas Neumann。

% Additionally, numerous people have contributed to the \pgfname\ system
% by writing emails, spotting bugs, or sending libraries and patches.
% Many thanks to all these people, who are too numerous to name them
% all!

另外，很多人通过写信、发现bugs、或发送库和补丁等对\pgfname\ 系统做出了
贡献。感谢他们所有人，因为人员很多，这里不一一列出。


% \subsection{Getting Help}
\subsection{获取帮助}

% When you need help with \pgfname\ and \tikzname, please do the
% following:
following:

在你使用\pgfname\ 和\tikzname\ 需要帮助时，请尝试如下方法：

\begin{enumerate}
\item
  % Read the manual, at least the part that has to do with your problem.
  阅读本手册，至少阅读问题涉及的部分。
\item
  % If that does not solve the problem, try having a look at the
  % sourceforge development page for \pgfname\ and \tikzname\ (see the
  % title of this document). Perhaps someone has already reported a
  % similar problem and someone has found a solution.
  如未能解决问题，就去看看\pgfname\ 和\tikzname\ 的开发页（参见本文档
标题）。也许有人已经报告了同样的问题，而某些人已经找到了解决办法。
\item
  % On the website you will find numerous forums for getting
  % help. There, you can write to help forums, file bug reports, join
  % mailing lists, and so on.
  在网上你可以找到很多论坛，从中获得帮助。在那里你可以获得帮助，报告
bug，加入邮件列表，等等。
\item
  % Before you file a bug report, especially a bug report concerning the
  % installation, make sure that this is really a bug. In particular,
  % have a look at the |.log| file that results when you \TeX\ your
  % files. This |.log| file should show that all the right files are
  % loaded from the right directories. Nearly all installation problems
  % can be resolved by looking at the |.log| file.
  在你提交一个bug报告特别是一个关于安装的bug报告之前，请确认确实存在这
个bug。尤其要看看在\TeX\ 编译文件时|.log|文件中的结果。|.log|文件会表
明所有在正确目录中加载的正确文件。几乎所有的安装问题都可以通过观察
|.log|文件得以解决。
\item
  % \emph{As a last resort} you can try to email me (Till Tantau) or, if
  % the problem concerns the mathematical engine, Mark Wibrow. I do
  % not mind getting emails, I simply get way too many of them. Because
  % of this, I cannot guarantee that your emails will be answered timely
  % or even at all. Your chances that your problem will be fixed are
  % somewhat higher if you mail to the \pgfname\ mailing list
  % (naturally, I read this list and answer questions when I have the
  % time).
  \emph{最后一招}就是给我写信了(Till Tantau)，或者关于数据引擎的问题
写给Mark Wibrow。因为数量太多，我其实不太关注收到的邮件。我因此不能保
证你的邮箱会被及时回复，有可能根本得不到回复。如果你写信发给\pgfname\
邮件列表中，解决问题的机会将会多少增加一些。（一般我在有时间时会阅读列
表并回答问题。）
\end{enumerate}

%%% Local Variables:
%%% mode: latex
%%% TeX-master: t
%%% End:
